↓Skip to main content
  1. posts/

Setting Up PHPUnit and GitHub Actions for a PHP Project

Programming Tutorial Testing DevOps PHP PHPUnit GitHub Actions

This tutorial shows you how to set up a basic PHP project with Composer, write tests using PHPUnit, and automate test execution with GitHub Actions. It’s intended for developers who want a clean starting point for building and testing PHP code.

You’ll create the project structure, configure Composer, add a simple test case, and define a GitHub Actions workflow to run tests on each push or pull request. By the end, you’ll have a fully working setup for local and automated testing.

Setting Up a PHP Project #

Before you begin, ensure that PHP and Composer are installed on your computer.

php --version
composer --version

Initialise Your PHP Project #

Create a folder for your project.

mkdir conditional-test-execution
cd conditional-test-execution

Initialize a new PHP project by running composer init in your project directory.

composer init

This will create a composer.json file. Ensure that your composer.json has the following structure.

{  
    "name": "software-witchcraft/conditional-test-execution",  
    "description": "A small demo project for showcasing conditional PHP test execution in GitHub Actions, created to support a tutorial.",  
    "type": "project",  
    "license": "mit",  
    "autoload": {  
        "psr-4": {  
            "SoftwareWitchcraft\\ConditionalTestExecution\\": "src/"  
        }  
    },  
    "authors": [  
        {  
            "name": "Software Witchcraft",  
            "email": "[email protected]"  
        }  
    ],  
    "require": {}  
}

Add PHPUnit as a Dependency #

Add PHPUnit via Composer. Run the following command in your project’s root directory.

composer require --dev phpunit/phpunit ^12

This command installs PHPUnit and its dependencies. The --dev flag indicates that PHPUnit is a development dependency, not required for the production environment.

Configure PHPUnit #

Create a phpunit.xml file in your project root. This file will hold your PHPUnit configuration. Here’s a basic example.

<phpunit bootstrap="vendor/autoload.php" colors="true">
    <testsuites>
	    <testsuite name="My Test Suite">
	        <directory>tests</directory>
	    </testsuite>
	</testsuites>
</phpunit>

In this file, bootstrap points to Composer’s autoloader, and the tests directory is where your test files will reside.

Write Your First Test #

Create file Greeter.php in your src folder …

touch ./src/Greeter.php

… with following content

<?php

namespace SoftwareWitchcraft\ConditionalTestExecution;

class Greeter
{
    public function greet(string $name): string
    {
        return 'Hello, ' . $name . '!';
    }
}

Create a tests directory in your project root.

mkdir tests

Inside this directory, create a test file, for example, GreeterTest.php …

touch ./tests/GreeterTest.php

… with a simple PHPUnit test class.

<?php 

use PHPUnit\Framework\TestCase;

use SoftwareWitchcraft\ConditionalTestExecution\Greeter;

class GreeterTest extends TestCase
{
    public function testGreetsWithName(): void
    {
        $greeter = new Greeter();

        $greeting = $greeter->greet('Alice');

        $this->assertSame('Hello, Alice!', $greeting);
    }
}

Running Tests Locally #

To run your tests, execute the following command in your project root:

./vendor/bin/phpunit --testdox

This command runs all the tests defined in your tests directory. PHPUnit will look for any files ending in Test.php and execute them.

Setup Git Repository and Push Your Project to GitHub #

Init you git repository.

git init

Create .gitignore file …

touch .gitignore

… with following content

/vendor/
/composer.lock
/.phpunit.result.cache
/.idea/
.DS_Store

Add and commit all your changes to your repository.

git add . 
git commit -m "initial commit"

Create a repository on GitHub, and link it to your local repository.

git remote add origin [email protected]:yourusername/your-repository-name.git

Don’t forget to update yourusername/your-repository-name!

Push your local repository to GitHub.

git push -u origin main

Now that we have our PHP project and PHPUnit setup complete, let’s move on to the next section where we will set up GitHub Actions to automate our testing process.

Setting Up the GitHub Actions Environment #

To start leveraging GitHub Actions, you need to set up a workflow. A workflow is a set of automated procedures and tasks that are executed based on defined events, like a push or a pull request.

Create a GitHub Actions Workflow File #

In your project repository, create directory .github/workflows.

mkdir -p ./.github/workflows

Inside this directory, create a new file named RunTests.yml (or any other name you prefer, but keep the .yml extension).

touch ./.github/workflows/RunTests.yml

Define the Workflow #

Start the YAML file with a name for the workflow and specify the trigger events. Commonly, workflows are triggered on push or pull request events. For example:

name: Run unit tests

on:
    push:
        branches: [ main ]
    pull_request:
        branches: [ main ]

jobs:
    build:
        runs-on: ubuntu-latest

        steps:
            - name: Check out repository code
              uses: actions/checkout@v4

            - name: Install PHP
              uses: shivammathur/setup-php@v2
              with:
                  php-version: '8.5' # Specify the PHP version
                  tools: composer:v2, phpunit:v9.6
                  coverage: none

            - name: Check PHP Version
              run: php -v

            - name: Install dependencies
              run: composer install # Install PHP dependencies

            - name: Run PHPUnit tests
              run: ./vendor/bin/phpunit --testdox # Execute PHPUnit tests

Commit and Push the Workflow File #

After setting up the RunTests.yml file, commit it to your repository and push it to GitHub:

git add .github/workflows/phpunit.yml
git commit -m "Add GitHub Actions workflow"
git push origin main

Once you push these changes to GitHub, the Run PHPUnit Tests workflow will be triggered on the next push or pull request to the main branch, automatically running your PHPUnit tests in the specified environment.

You’ve now set up a complete PHP project with local testing using PHPUnit and automated test execution via GitHub Actions. This setup helps ensure your code stays reliable by catching issues early with every push or pull request. From here, you can continue building features, adding more tests, and extending your CI workflow as needed.

The complete code for this project is available in the GitHub repository. You can explore the structure, test setup, and workflow configuration in one place and use it as a reference or starting point for your own projects.